Add ListInParaSniff to flag lists wrapped in a <para>#17
Conversation
|
This is a good sniff to add, however it's too aggressive.
For example the following is allowed. <para>
The following constants are defined, and represent possible
<function>exif_imagetype</function> return values:
<table>
<title>Imagetype Constants</title>
...
</table>
</para>When building new sniffs it's important to measure performance. To get a more detailed measurement, you can use the Some things that we may consider here depending on what gives the least overhead.
XPath would be the cleanest IMHO as it avoids a nested loop. |
Flag a list or table only when it is the sole child of the <para> and the <para> carries no text of its own, so an intro sentence followed by a <table> stays allowed. Add <table>/<informaltable> to the set and select candidates with a single XPath pass instead of a nested loop.
An element name containing an apostrophe or any non-NCName character would be injected verbatim into the XPath predicate, making the query invalid and silently disabling the whole sniff. Drop such values and keep the defaults.
|
As commented, it is probably way faster to XPath search all "child" elements first, without |
|
I ran the benchmark on the full doc-en reference directory (10 837 files) with both approaches:
The current XPath turns out to be ~2.5x faster, likely because there are far fewer nodes with direct block children to inspect than total occurrences of the disallowed elements across the whole tree. |
|
Interessing. And go with the faster alternative. |
Adds a sniff that flags list elements (
simplelist,variablelist,itemizedlist,orderedlist) nested directly inside a<para>. In the PHP manual these belong as a direct child of the containing section, and wrapping them in a<para>is a recurring style/build issue.It checks the list's immediate parent, so a list nested deeper (e.g. inside a
<note>) is not flagged. AnadditionalListElementsoption allows extending the set. Registered indocbookcs.xml.dist.Open questions for you: is the element set right (should
<table>/<informaltable>be included too?), and iserrorthe right default severity?